Sparking Joy in Code

Avoid hasty abstractions#

“Hell does not understand my own code.”

- Kyle Simpson

Code is read more than it is written. If your code isn’t a joy to read, it will be difficult to use and dreadful to refactor. Avoid hasty abstractions as much as possible.

We constantly need reminders to avoid code complexity:

• From Fred Brooks warning us about accidental complexity to Rich Hickey exhorting us to decomplect
• From Bob Martin teaching us to write Clean Code to Kent Beck teaching us to write sensible tests for them
• From Sophie Alpert (former manager of React) encouraging us to facilitate local reasoning to Dan Abramov showing us to design code that is Optimized for Change

Give good names#

Everyone knows naming things is hard; there are many opinions here. If something is too complicated to give a good name to it, you’re probably giving it too much responsibility.

Write comments#

Heed your code readability as a code smell.

“Comments explain why code explains the how.”

- Jem Young

Code comments are a developer communication cheat code. They don’t have any performance impact (usually!) and can help avoid others wasting time.

How to write good comments#

Instead of explaining what the code is doing, which is often evident from just reading the code itself and liable to go out of date when code is changed, you can:

• Try to note why some choices were made
• Consider why the “obvious” approach wasn’t chosen
• Give an ASCII art diagram of how the code works.

When you anticipate what I’m going to ask as I read your code, believe me, that sparks joy.

Purpose of comments#

According to Sarah Drasner (elaborated in talk form here), comments can serve these other good purposes as well:

• Clarifying something that is not legible by regular human beings
• Break up chunks of code, like chapters of a book
• Pseudocode to keep the logic straight while writing the code
• Indicating TODOs or what parts of code are okay to refactor
• Serving as a teaching tool to fellow teammates
• Admitting where you got it from StackOverflow

"I think the best written, most elegant code in the world cannot compare even remotely to well done, natural language documentation when it comes to communicating the intention and context of what was built, how this thing works, why we built this thing. The code can explain what it does and at a technical level how it does it, but it doesn’t explain the business reasons and impact, or even some of the other systems that might depend on it.

A lot of people underestimate the value to the doc writer of having to sit down and write those docs… You might discover things about what you just built and realize: ‘Oh wait, I missed something!’"

- Jared Short

Great error design#

Great error design sparks joy. Developers often write services and modules to be used by other developers, even within the same app. Most of these interactions will be governed by some sort of contract, explicitly specified by design documents, an OpenAPI spec, or something similar.

However, what is usually underspecified is what to do when things go wrong:

• A normal error message tells you an error happened somewhere.
• A good error message tells you the local state that caused the error.
• A great error message tells you probable causes and how to fix them.
• A terrible error design doesn’t show up at all; it’s a silent error.

Never normalize errors#

The number of error messages also matters. Never normalize errors. Don’t cry wolf. If you train people that they can ignore your errors, they will ignore important errors, and you will get lazy about when and how you make an error. You can at least have a hierarchy of errors. Simple info, warning, or error hierarchy will usually do, but you can explore Syslog severity levels for something more formally designed.

Make your errors as lazy as possible#

Erroring too eagerly can also cause a lot of start-and-stop debugging. Instead, make your errors as lazy as possible. If the program doesn’t necessarily have to stop, don’t. Use a notify() function that users can configure to buffer and log these errors.

Write code others enjoy reading and using#

You might expect these things to be covered in code standards documents, but code standards usually address the minimum required standards (for a good reason, to avoid being onerous). To spark joy, we look for opportunities to go above and beyond. One way to be a developer that others enjoy working with is to write code others enjoy reading and using.